kzu_message_dispatcher.h File Reference

Message dispatcher. More...

#include "kzu_message_type.h"
#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <system/kzs_header.h>

Macros
#define	KZU_MESSAGE_DISPATCHER_NO_LIMIT
	A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used. More...

Typedefs
typedef kzsError(*	KzuMessageHandlerFunction )(struct KzuMessage *message, void *userData)
	Message callback prototype. More...
typedef kzsError(*	KzuMessageDispatchFunction )(const struct KzuMessage *message, void *userData)
	Application message callback prototype. More...

Enumerations
enum	KzuTimerMessageMode { KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT, KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH }
	Timer mode. More...

Functions
kzsError	kzuMessageDispatcherCreate (const struct KzcMemoryManager *memoryManager, struct KzuMessageDispatcher **out_messageDispatcher)
	Create a message dispatcher. More...
kzsError	kzuMessageDispatcherDelete (struct KzuMessageDispatcher *messageDispatcher)
	Destroy a message dispatcher. More...
void	kzuMessageDispatcherSetInputManager (struct KzuMessageDispatcher *messageDispatcher, struct KzuInputManager *inputManager)
	Set an input manager for a dispatcher. More...
struct KzuInputManager *	kzuMessageDispatcherGetInputManager (const struct KzuMessageDispatcher *messageDispatcher)
	Get the input manager from a dispatcher. More...
void	kzuMessageDispatcherSetTaskScheduler (struct KzuMessageDispatcher *messageDispatcher, struct KzuTaskScheduler *taskScheduler)
	Set a task scheduler for a dispatcher. More...
struct KzuTaskScheduler *	kzuMessageDispatcherGetTaskScheduler (const struct KzuMessageDispatcher *messageDispatcher)
	Get the task scheduler from a dispatcher. More...
void	kzuMessageDispatcherSetMessageLimit (struct KzuMessageDispatcher *messageDispatcher, kzUint limitThreshold, kzUint limitPerFrame)
	Sets the limitation of how many messages can be processed per frame. More...
kzsError	kzuMessageDispatcherCreateMessage (struct KzuMessageDispatcher *messageDispatcher, const struct KzuMessageType *messageType, struct KzuMessage **out_Message)
	Creates a message object. More...
kzsError	kzuMessageDispatcherAddHandler (const struct KzuMessageDispatcher *messageDispatcher, struct KzuObjectNode *subscriptionSiteNode, const struct KzuMessageType *messageType, struct KzuObjectNode *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler. More...
kzsError	kzuMessageDispatcherAddTunnellingHandler (const struct KzuMessageDispatcher *messageDispatcher, struct KzuObjectNode *subscriptionSiteNode, const struct KzuMessageType *messageType, struct KzuObjectNode *messageSource, KzuMessageHandlerFunction handlerFunction, void *userData)
	Adds a message handler for tunneling phase. More...
kzsError	kzuMessageDispatcherIsHandlerSubscriptionValid (const struct KzuMessageDispatcher *messageDispatcher, const struct KzuObjectNode *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData, kzBool *out_valid)
	Checks if a handler subscription is valid. More...
kzsError	kzuMessageDispatcherRemoveHandler (const struct KzuMessageDispatcher *messageDispatcher, const struct KzuObjectNode *subscriptionSiteNode, const struct KzuMessageType *messageType, KzuMessageHandlerFunction handlerFunction, const void *userData)
	Removes a message handler. More...
kzsError	kzuMessageDispatcherDispatchMessage (const struct KzuMessageDispatcher *messageDispatcher, struct KzuMessage *message, struct KzuObjectNode *source)
	Dispatches a message. More...
kzsError	kzuMessageDispatcherDispatchMessageSynchronous (const struct KzuMessageDispatcher *messageDispatcher, struct KzuMessage *message, struct KzuObjectNode *source)
	Dispatches a message. More...
kzsError	kzuMessageDispatcherDispatchQueuedMessages (struct KzuMessageDispatcher *messageDispatcher)
	Dispatches queued messages. More...
kzsError	kzuMessageDispatcherNotifyObjectDeleted (const struct KzuMessageDispatcher *messageDispatcher, const struct KzuObjectNode *objectNode)
	Notifies the message dispatcher that an object node is being destroyed. More...
kzsError	kzuMessageDispatcherAddTimerHandler (const struct KzuMessageDispatcher *messageDispatcher, kzUint interval, enum KzuTimerMessageMode mode, KzuMessageHandlerFunction handlerFunction, void *userData)
	Registers a timer handler. More...
kzsError	kzuMessageDispatcherRemoveTimerHandler (const struct KzuMessageDispatcher *messageDispatcher, KzuMessageHandlerFunction handlerFunction, const void *userData)
	Unregisters a timer handler. More...
kzUint	kzuMessageDispatcherGetTime (const struct KzuMessageDispatcher *messageDispatcher)
	Returns current time of message dispatcher in milliseconds. More...
void	kzuMessageDispatcherSetCurrentData (struct KzuMessageDispatcher *messageDispatcher, struct KzuPropertyManager *propertyManager)
	Sets property manager for message dispatcher. More...
void	kzuMessageDispatcherSetCallbackUserData (struct KzuMessageDispatcher *messageDispatcher, void *userData)
	Set the user data passed to the callbacks set with kzuMessageDispatcherSetCallbackUserData and kzuMessageDispatcherSetHandlerSetFloatProperty. More...
void	kzuMessageDispatcherSetHandlerSetBooleanProperty (struct KzuMessageDispatcher *messageDispatcher, KzuMessageDispatchFunction function)
	Set a callback to handle the KZU_MESSAGE_SET_BOOLEAN_PROPERTY and KZU_MESSAGE_TOGGLE_BOOLEAN_PROPERTY messages. More...
void	kzuMessageDispatcherSetHandlerSetFloatProperty (struct KzuMessageDispatcher *messageDispatcher, KzuMessageDispatchFunction function)
	Set a callback to handle the KZU_MESSAGE_SET_FLOAT_PROPERTY message. More...

Detailed Description

Message dispatcher.

Provides a system to exchange messages between different parts of an application. Messages can be used to notify of an event or request operations and data.

Copyright 2008-2019 by Rightware. All rights reserved.

Macro Definition Documentation

#define KZU_MESSAGE_DISPATCHER_NO_LIMIT

A constant for kzuMessageDispatcherSetMessageLimit indicating that no message limit should be used.

Typedef Documentation

typedef kzsError(* KzuMessageHandlerFunction)(struct KzuMessage *message, void *userData)

Message callback prototype.

typedef kzsError(* KzuMessageDispatchFunction)(const struct KzuMessage *message, void *userData)

Application message callback prototype.

Enumeration Type Documentation

enum KzuTimerMessageMode

Timer mode.

Enumerator
KZU_TIMER_MESSAGE_MODE_ONCE	Timer will be called once after the specified interval elapses. Unsubscribe still needed.
KZU_TIMER_MESSAGE_MODE_REPEAT	Timer will be called repeatedly at specified intervals. Timers in this mode should be disabled when the application update cycle is called infrequently, for example in low power situations, as this generates excessive number of messages.
KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH	Same as KZU_TIMER_MESSAGE_MODE_REPEAT, but the system dispatches only the last message when a timer has several pending messages.

Function Documentation

kzsError kzuMessageDispatcherCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuMessageDispatcher **	out_messageDispatcher
	)

Create a message dispatcher.

kzsError kzuMessageDispatcherDelete

(

struct KzuMessageDispatcher *

messageDispatcher)

Destroy a message dispatcher.

void kzuMessageDispatcherSetInputManager	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuInputManager *	inputManager
	)

Set an input manager for a dispatcher.

struct KzuInputManager* kzuMessageDispatcherGetInputManager

(

const struct KzuMessageDispatcher *

messageDispatcher)

Get the input manager from a dispatcher.

void kzuMessageDispatcherSetTaskScheduler	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuTaskScheduler *	taskScheduler
	)

Set a task scheduler for a dispatcher.

struct KzuTaskScheduler* kzuMessageDispatcherGetTaskScheduler

(

const struct KzuMessageDispatcher *

messageDispatcher)

Get the task scheduler from a dispatcher.

void kzuMessageDispatcherSetMessageLimit	(	struct KzuMessageDispatcher *	messageDispatcher,
		kzUint	limitThreshold,
		kzUint	limitPerFrame
	)

Sets the limitation of how many messages can be processed per frame.

If the number of messages exceeds limitThreshold, a warning is logged and the remaining messages are discarded. KZU_MESSAGE_DISPATCHER_NO_LIMIT disables the limitation (default). After the threshold has been exceeded once, subsequent frames will process at most limitPerFrame messages to ensure good framerate.

kzsError kzuMessageDispatcherCreateMessage	(	struct KzuMessageDispatcher *	messageDispatcher,
		const struct KzuMessageType *	messageType,
		struct KzuMessage **	out_Message
	)

Creates a message object.

Parameters

messageDispatcher	The message dispatcher to use.
messageType	Type of the message.
out_Message	A pointer set to point to the new message.

kzsError kzuMessageDispatcherAddHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuObjectNode *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		struct KzuObjectNode *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler.

Parameters

messageDispatcher	The message dispatcher to use.
subscriptionSiteNode	Object node that is associated with the message subscription created by this function.
messageType	Type of the message to match.
messageSource	Source of the message (as returned by kzuMessageGetSource) to match.
handlerFunction	Function to call when a matching message appears.
userData	User data pointer passed to handlerFunction.

kzsError kzuMessageDispatcherAddTunnellingHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuObjectNode *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		struct KzuObjectNode *	messageSource,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Adds a message handler for tunneling phase.

kzsError kzuMessageDispatcherIsHandlerSubscriptionValid	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const struct KzuObjectNode *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData,
		kzBool *	out_valid
	)

Checks if a handler subscription is valid.

kzsError kzuMessageDispatcherRemoveHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const struct KzuObjectNode *	subscriptionSiteNode,
		const struct KzuMessageType *	messageType,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Removes a message handler.

kzsError kzuMessageDispatcherDispatchMessage	(	const struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuMessage *	message,
		struct KzuObjectNode *	source
	)

Dispatches a message.

The associated handlers are called when kzuMessageDispatcherDispatchQueuedMessages is called.

kzsError kzuMessageDispatcherDispatchMessageSynchronous	(	const struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuMessage *	message,
		struct KzuObjectNode *	source
	)

Dispatches a message.

The associated handlers are called immediately.

kzsError kzuMessageDispatcherDispatchQueuedMessages

(

struct KzuMessageDispatcher *

messageDispatcher)

Dispatches queued messages.

Generally should be called once per frame.

kzsError kzuMessageDispatcherNotifyObjectDeleted	(	const struct KzuMessageDispatcher *	messageDispatcher,
		const struct KzuObjectNode *	objectNode
	)

Notifies the message dispatcher that an object node is being destroyed.

This will cancel all messages where the specified node is the source of the message or the current site during routing.

kzsError kzuMessageDispatcherAddTimerHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		kzUint	interval,
		enum KzuTimerMessageMode	mode,
		KzuMessageHandlerFunction	handlerFunction,
		void *	userData
	)

Registers a timer handler.

Parameters

messageDispatcher	The message dispatcher to use.
interval	timeout in milliseconds in case of a one-shot timer, and the interval in case of a repeating timer.
mode	KZU_TIMER_MESSAGE_MODE_ONCE, KZU_TIMER_MESSAGE_MODE_REPEAT or KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH. KZU_TIMER_MESSAGE_MODE_REPEAT_BATCH is recommended for a repeating timer because it calls handlerFunction only once when the interval has been exceeded several times over.
handlerFunction	The function to call when the timer expires.
userData	User data pointer passed to handlerFunction.

kzsError kzuMessageDispatcherRemoveTimerHandler	(	const struct KzuMessageDispatcher *	messageDispatcher,
		KzuMessageHandlerFunction	handlerFunction,
		const void *	userData
	)

Unregisters a timer handler.

kzUint kzuMessageDispatcherGetTime

(

const struct KzuMessageDispatcher *

messageDispatcher)

Returns current time of message dispatcher in milliseconds.

void kzuMessageDispatcherSetCurrentData	(	struct KzuMessageDispatcher *	messageDispatcher,
		struct KzuPropertyManager *	propertyManager
	)

Sets property manager for message dispatcher.

void kzuMessageDispatcherSetCallbackUserData	(	struct KzuMessageDispatcher *	messageDispatcher,
		void *	userData
	)

Set the user data passed to the callbacks set with kzuMessageDispatcherSetCallbackUserData and kzuMessageDispatcherSetHandlerSetFloatProperty.

void kzuMessageDispatcherSetHandlerSetBooleanProperty	(	struct KzuMessageDispatcher *	messageDispatcher,
		KzuMessageDispatchFunction	function
	)

Set a callback to handle the KZU_MESSAGE_SET_BOOLEAN_PROPERTY and KZU_MESSAGE_TOGGLE_BOOLEAN_PROPERTY messages.

void kzuMessageDispatcherSetHandlerSetFloatProperty	(	struct KzuMessageDispatcher *	messageDispatcher,
		KzuMessageDispatchFunction	function
	)

Set a callback to handle the KZU_MESSAGE_SET_FLOAT_PROPERTY message.